Improve contribute section #32
Conversation
latest commit adds a distinct title to the development docs for the cli
seems like we could just as easily add https://github.com/nextstrain/.github as a submodule and render it here if we want
|
Hm, seems like the symbolic link approach did not translate from my local environment to read the docs' build: https://readthedocs.org/projects/nextstrain/builds/12140142/. I'll look into this. |
|
I tried an alternative method (which seems better in theory than using symlinks, since symlinks are potentially confusing and it avoids them) of sourcing the readme in the build. For details see: https://github.com/nextstrain/docs.nextstrain.org/compare/improve-contribute...improve-contribute-readme?expand=1 It was basically this:
However, if you look at https://docs.nextstrain.org/en/improve-contribute-readme/guides/contribute/index.html, the Contributing to Documentation entry (aka the readme) does not show up. I'm not sure why this is, as this approach also worked locally, as did the symlink approach. I couldn't find anything obvious in build logs. Maybe there are simpler ways or taking a step back maybe including this repo's readme in the sphinx build is not something we want or need at the end of the day. @tsibley do you have experience with this? One alternative is if we really thing most of the content in the readme belongs in the docs, we can move it to an actual document there and then link to it from the readme. |
|
6973b7a adds a "Contributing to Documentation" page with a link out to the readme: https://docs.nextstrain.org/en/improve-contribute/guides/contribute/documentation.html This solves the above issue about including the readme, and we can improve on this later as we see fit. @jameshadfield merge away if this works for you! |
See #31 for the goal of this and see commit messages for implementation details.
My implementation of
uses symbolic links as per sphinx-doc/sphinx#2840 (comment) to include the readme in the build of these docs as a guide for contributing documentation. There are other suggestions for how to do something like this in that thread.